|
|
MeasureJustified |
||||
| Header: | QuickdrawText.h | Carbon status: | Supported | |
Calculates, for text that is expanded, condensed, or scaled, the onscreen width in pixels from the left edge of the text segment to the glyph of the character.
void MeasureJustified (
Ptr textPtr,
SInt32 textLength,
Fixed slop,
Ptr charLocs,
JustStyleCode styleRunPosition,
Point numer,
Point denom
);
A pointer to the memory location of the beginning of the text to be measured.
The number of bytes of text to be measured. The text length should equal the entire visible part of the text on a line, including trailing spaces if and only if they are displayed. Otherwise, the results for the last glyph on the line may be invalid.
The amount of slop for the text to be drawn. A positive value extends the text segment; a negative value condenses the text segment.
The value of this parameter is the number of pixels by which the width of the text segment is to be changed, after the text has been scaled. The slop is a signed value that specifies how much the text is to be extended or condensed. The slop is derived from the calculations made using the proportion returned from the PortionLine function for a style run. To measure or draw text that is not to be extended or condensed, pass a slop value of 0.
A pointer to an application-defined array of textLength + 1 integers.
The position on the line of this style run. The style run can be the only one on the line, the leftmost on the line, the rightmost on the line, or one between two other style runs.
This parameter specifies the position of the style run on the display line. It is used to determine the proportion of total slop to apply to a style run, measure or draw a line of justified text, identify where to break a line of text, and determine the caret position to mark an insertion point or highlight text.
The style run position parameter is meaningful only for those script systems that use intercharacter spacing for justification. For all other script systems, the parameter exists for future extensibility. Although the style run position parameter is not used, for example, for justifying text in the Roman script system, to allow for future compatibility, you should always specify the appropriate value for it for all calls that take it.
For those script systems that do use intercharacter spacing, space between style runs may be allocated differently depending upon whether the style run is leftmost, rightmost, or between two other style runs. For example, depending on the script system, if a style run occurs at the beginning or end of a line, extra space may not be added to the outer edge of the outermost glyph, whereas if a style run is interior to a line, all of the glyphs of the text may be treated the same: extra space is allocated to both sides of every glyph including those at either end of the style run.
The current implementations of simple script systems such as Roman and Cyrillic do not justify a line of text by changing the width of nonspace characters. Instead, they rely solely on the use of space characters: the same amount of extra width is added to (or subtracted from) every space whether the space is at the beginning or end of the line or interior to it.
A point giving the numerator for the horizontal and vertical scaling factors.
Both numer and denom are point values: numer specifies the numerator for the horizontal and vertical scaling factors, and denom specifies the denominator for the horizontal and vertical scaling factors. Together, these values specify the scaling factors for the text: numer.v over denom.v gives the vertical scaling (height), and numer.h over denom.h gives the horizontal scaling factors (width). You need to specify values for numer and denom even if you are not scaling the text. For unscaled text, you can specify scaling factors of 1, 1.
A point giving the denominator for the horizontal and vertical scaling factors.
The MeasureJustified function is similar to the MeasureText function, except that it is used to find the pixel location of a character’s glyph in text that is expanded or condensed. The function calculates the onscreen pixel width of the glyph of each character, beginning from the left edge of the text segment, taking into account slop value, scaling, and style run position.
On return, the first element in the charLocs array contains 0 and the last element contains the total width of the text segment, when the primary line direction is left to right and the text is unidirectional. When the primary line direction is right to left and the text is unidirectional, the first element in the array contains the total width of the text segment, and the last element in the array contains 0. When the text is bidirectional, at a direction boundary, MeasureJustified selects the character whose direction maps to that of the primary line direction.
The MeasureJustified function returns the same results that an application would get if it called CharToPixel for each character with a direction parameter value of hilite. Using MeasureJustified to find the pixel location of a character’s glyph is less efficient than using the CharToPixel function because the application must define the array pointed to by charLocs, and then walk the array after MeasureText returns the results.
The MeasureJustified function temporarily resets the space extra (spExtra) value, adding to the current value of the field, if any, the amount of extra space to be added to space characters in order to fully justify the text, based on calculations that take into account the slop value and all the text characteristics. On exit, MeasureJustified restores the original value.
Because MeasureJustified measures text in only the current font, style, and size, you need to call it once for each individual style run. For additional information about MeasureJustified, contact Developer Technical Support.
The MeasureJustified function works properly for text in all script systems. For 1-byte complex script systems, MeasureJustified calculates the widths of any ligatures, reversals, and compound characters that would need to be drawn.
Note that textLength is the number of bytes to be drawn, not the number of characters. Because 2-byte script systems also include characters consisting of only one byte, you should not simply multiply the number of characters by 2 to determine this value; the application must determine and specify the correct number of bytes.
Some 1-byte script system fonts may have zero-width characters, which are usually overlapping diacritical marks that typically follow the base character in memory. In this case, MeasureJustified measures both the glyph of the base character (the high-order, low-address byte) and the width of the diacritical mark. The charLoc array includes an entry for each, but both entries contain the same value.
For 1-byte complex script systems, MeasureJustified calculates the widths of any ligatures, reversals, compound characters, and character clusters that need to be drawn. For example, for an Arabic ligature, the entry that corresponds to the trailing edge of each character that is part of the ligature is the trailing edge of the entire ligature.
The MeasureJustified function may move memory; do not call this function at interrupt time.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)